Clean Code - Comments Best Practices

코드로 의도를 표현하라!

대부분 주석을 보면 코드로 설명이 다 안 되니까 이해시키려고 달아논 코드입니다.

그러지 말고 코드에 개발자의 의도를 표현하는 방법을 사용하자.

예)

javascript

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

if 조건이 아주 길고 어렵기 때문에 위에 주석을 달아논 것을 볼 수 있습니다.

javascript

if (employee.isEligibleForFullBenefits())

주석을 제거하고 위처럼 의도가 나타나게 코드를 변경하니 주석이 없이도 술술 읽힌다.

좋은 주석

1. 법적인 주석

코드 배포 license를 명시할 때 사용하는 주석은 소유권 정보로 주석으로 타당하다.

javascript

// Copyright (c) 2019, 2020, 2021 by Effort Guy, All rights reserved.
// GNU General Public License 버전 2 이상을 따르는 조건으로 배포한다.

2. 정보를 제공하는 주석

아래 주석은 사실 주석이 없어도 이해할 수는 있지만 바로 이해하기 힘들기 때문에 괜찮은 주석이다.

javascript

// kk:mm:ss EEE, MMM dd, yyyy 형식이다.
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");

위처럼 안 하고 메소드로 따로 빼서 의도를 표현한 이름을 사용하면 주석이 필요없을 거 같다.

3. 의미를 명료하게 밝히는 주석

표준 라이브러리나 변경하지 못하는 코드에 속하는 모호한 인수나 반환값의 의미를 명료하게 밝히는 주석은 괜찮은 주석이다.

변경할 수 있으면 명확한 이름을 쓰면 된다.

javascript

assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != b
assertTrue(a.compareTo(b) == -1); // a < b
assertTrue(a.compareTo(b) == 1); // a > b

4. 결과를 경고하는 주석

실행 결과를 미리 경고 하는 주석은 괜찮은 주석이다.

javascript

// 평균 10분 정도 걸리는 작업입니다.
public void calcBalance()...

5. Todo, Fixme 주석

IDE에서 인식할 수 있는 주석을 사용하는 것도 괜찮은 방법이다.

Todo : 해야 할 일

Fixme : 수정 할 작업

Todo, Fixme 주석을 달아 놓으면 IDE에서 해당 주석만 몰아서 볼 수 있다.

javascript

// Todo 로그를 추가해야 함
private Order getOrder()...

// Fixme 간헐적으로 디코딩 에러가 발생함
private Student getStudent()...

6. 중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨서 지우거나 수정하면 절대 안 되는 부분에 강조를 위한 주석을 사용한다.

javascript

// 여기서 trim은 반드시 필요하다. 공백으로 시작하는 문자열이 가끔 들어오기 때문이다.
String listItemContent = match.group(3).trim()

7. Javadocs

공개 API나 회사 내에서 공통으로 쓰고 있는 모듈에 달아 놓으면 좋다.

위 처럼 javadocs를 달아놓으면 IDE가 아주 깔끔하게 잘 보여준다.

8. 주석같은 annotation

함수, 변수가 변경되어서 삭제된다는 걸 주석으로도 남길 수 있지만 주석보단 annotation이 더 눈에 띄고 좋다.

@Deprecated : 어느 시점이후로 사라지게 될 부분이다라는 뜻의 어노테이션

아래처럼 Javadocs에 언제부터 없어질지를 적어도 되는데

@Deprecated(since = "1.3")

이런 식으로 since에 언제부터 사라지는 건지에 대한 시점을 적어줄 수 있다.

이외에도

@NotThreadSafe : 쓰레드 세이프하지 않다.

@Nullable : Null이 허용된다

@NonNull : Null이 허용되지 않는다.

가 있다.

나쁜 주석

작성된 주석 대부분이 나쁜 주석에 포함된다.

1. 주절거리는 주석

개발자 자신만 알아듣게 주절거리는 식으로 써놓은 주석

예)

javascript

public void loadProperties() {
	try {
		loadedProperties.load(propertiesStream);
	} catch (IOException e) {
		// 속성 파일이 없다면 기본 값을 모두 메모리로 읽어 들였다는 의미다.
	}
}

catch에 어떤 작업을 하려고 주석을 달아 놓은 것인가? 아니면 나중에 작업을 하려고 써놓은 주석인가?

확실하지 않기 때문에 로직을 까볼 수 밖에 없다.

이해가 되지 않고 개발자 자신만 아는 말로 써놓는 건 최악이다.

2. 코드와 동일한 내용을 써놓은 주석

예) 헤더에 달린 주석이 아래 코드 내용과 동일하다. 주석 읽을 시간에 코드 읽는 게 더 빠르다.

javascript

// this.closed가 true일 때 반환되는 유틸
// 타임아웃에 도달하면 예외를 던짐
public synchronized void waitForClose(final long millis) throws Exception {
	if(!closed) {
		wait(millis);
		if(!closed) throw new Exception();
	}
}

3. 애매한 정보가 있는 주석

딱히 예를 들필요가 없다.

주석이 달린 로직을 상세히 적지 않고 오해할만하게 일부만 적은 그런 쓸모없는 주석

4. 의무적으로 다는 주석

모든 메소드의 인자를 그냥 아무 의미없이 의무적으로 다는 주석은 별로다.

javascript

/**
 *
 * @param title CD 제목
 * @param author CD 저자
 */
public void addCD(String title, String author) {
	CD cd = new CD();
	cd.title = title;
	cd.author = author;
	cds.add(cd);
}

만약 회사 내부 방침으로 저렇게 다 적어야 한다면 회사 방침을 다시 고려해볼 필요가 있다.

5. 이력을 기록하는 주석

소스에 주석으로 이력을 관리하는 주석은 별로다.

git이 다 해주기 때문에 불필요하다.

javascript

/**
 *
 * 2021년 10월 21일 : 클래스를 정리하고 불필요한 getMember 메소드 삭제
 * 2021년 10월 25일 : getMember 메소드를 다시 추가
 * 2021년 12월 20일 : 클래스 명을 Member -> Customer로 변경
 */

6. 있으나 마나 한 주석

저런 쓸모없는 주석을 다는 사람이 있나?

javascript

// 기본 생성자
protected Member() {}

7. 함수나 변수로 표현할 수 있다면 주석을 달지 마라

java

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

if 조건에 주석을 달지말고 아래처럼 읽자마자 이해가 가게 표현하자.

javascript

if (employee.isEligibleForFullBenefits())

8. 주석으로 처리한 코드

이제는 쓸모없어진? 아니면 잠깐만 주석처리를 해논?

도대체 무슨 의미로 주석처리해놨는지 알 수가 없는 코드는 괜한 오해만 생기게 만든다.

javascript

return getMember();
// updateMember();
// return member;

책엔 더 많은 예제들이 있는데 솔직히 이렇게까지 불필요한 주석을 다는 사람들이 있을까 싶어서 그나마 좀 있을법한 주석 예제들을 넣었습니다.

사실 이번 장에서 하려는 얘기는 단 하나입니다.

부정확하고 코드로 나타낼 수 있는 주석은 필요없다.

정말 필요할 때만 주석을 넣자 정말정말 필요할 때.

Clean Code - Comments Best Practices ​

코드로 의도를 표현하라! ​

좋은 주석 ​

나쁜 주석 ​

Clean Code - Comments Best Practices

코드로 의도를 표현하라!

좋은 주석

나쁜 주석